package bigbrother.modules;

import bigbrother.IrcBotContext;
import bigbrother.command.Command;
import bigbrother.core.ChannelListener;
import org.apache.wicket.Component;

import java.util.Collection;
import java.util.Properties;

/**
 * Interface that modules should implement to provide some commands.
 * <p/>
 * A module can be started and stopped.  Typically modules are started when the irc bot has connected to a server, and
 * closed when the irc bot is gracefully shut down.
 *
 * @author Hans Haggstrom
 */
// IDEA: The irc bot framework could maintain a basic website / page, and different modules could provide
// subpages that get automatically linked from the main page.  Maybe a bit portal style.
// Some ideas: logging, with bookmarks, user online statistics, social graph of user interactions, portal to access some other application, etc.    
public interface Module
        extends ChannelListener
{

    /**
     * @return unique identifier for this Module.
     */
    String getIdentifier();

    /**
     * Called when the module is started up / initialized.
     *
     * @param context    the context providing methods that the module can call.
     * @param properties the properties for this irc bot.
     */
    void start( IrcBotContext context, Properties properties );

    /**
     * Called when the module is shut down for some reason.
     */
    void stop();

    /**
     * Called when a command is called for a specific module by some user.
     *
     * @param channel    The channel on which the command was sent, or null if it was sent as a private message.
     * @param sender     The nick of the person who sent the command.
     * @param login      The login of the person who sent the command.
     * @param hostname   The hostname of the person who sent the command.
     * @param command    The command sent to the module.
     * @param parameters The parameter string for the command.
     */
    void handleCommand( final String channel,
                        final String sender,
                        final String login,
                        final String hostname,
                        final String command,
                        final String parameters );

    /**
     * @return a read only list with the available commands in this module.
     */
    Collection<Command> getCommands();

    /**
     * A way for modules to provide content to the IRC bot web page.
     * <p/>
     * Remember that the web components can be created and run in different threads than the module, so syncronize your
     * access to the module from the web component.
     *
     * @param id the id to use for the web component.
     *
     * @return creates a new Wicket {@link Component} that should be used for this module on the main portal page.
     *         Return null if this module has no web UI.
     */
    Component createWebComponent( final String id );
}
